lab components / Forms and input

Auto Complete

Enable users to input a single line of text and suggests options as they type.

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { AutoComplete } from "@siteimprove/fancylab";

#Examples

The AutoComplete component is a single-line text input field that dynamically suggests options from a pre-defined list based on user input. It is designed to improve the user experience by reducing the number of keystrokes required to complete a task and increasing the accuracy of input.

#Variant overview:

Variant	Purpose	Usage guideline
Default	Selecting from a known, predefined list of options.	Suggestions update in real-time as the user types.
Async	Filtering through large or dynamic datasets sourced from a database or API.	Fetches suggestions on-the-fly; includes loading indicator during retrieval.
Invalid	Informing the user of incorrect input that doesn't match available options or violates validation rules.	Inherits styles from the Input Field component; displays clear error messages.
Disabled	When the Autocomplete is temporarily unavailable or irrelevant in the current context.	Prevents user interaction; can include a hint text or a visual clue explaining the disabled state.

#Default

The default variant is the primary mode for user interaction. It functions by dynamically updating the list of suggestions in real time as the user types, making it ideal for scenarios where users need to select from a predefined set of options. To ensure a clear and uncluttered user experience, it's recommended to limit the number of suggestions displayed simultaneously.

Composition:

Input field: The primary area where users type their query.
Suggestion list: A dynamic list of options appears below the input field, updating as the user types, with matched text highlighted.
Loading indicator: A visual cue (e.g., spinner) indicating suggestions are being fetched from an external source.
Error message: Clear feedback displayed when the input is invalid or doesn't match available options.

CodeHTML output

const [value, setValue] = useState("");
return (
	<AutoComplete
		suggestions={[
			"Apple",
			"Banana",
			"Blueberry",
			"Cherry",
			"Grape",
			"Guava",
			"Lemon",
			"Lime",
			"Orange",
			"Peach",
			"Pear",
			"Pineapple",
			"Raspberry",
			"Strawberry",
			"Watermelon",
		]}
		value={value}
		onChange={setValue}
		name="fruit"
		placeholder="Type a fruit"
		aria-label="List of fruits"
	/>
);

#Async

The Async variant is designed to handle situations where the list of suggestions is extensive or needs to be dynamically updated. It retrieves options from an database or API, or hard-coded into the component, eliminating the need to load all possibilities upfront. During the retrieval process, a Spinner is displayed to provide visual feedback to the user.

CodeHTML output

const [suggestions, setSuggestions] = useState<string[]>([]);
const [value, setValue] = useState<string>("");
const [loading, setLoading] = useState<boolean>(false);
const debouncedSearch = useDebounceFn(onSearch, 500);

async function onSearch(searchQuery: string, caseSensitive: boolean) {
	const data = await api.searchFruits(searchQuery, caseSensitive);
	setSuggestions(data.map((fruit) => fruit.name));
	setLoading(false);
}

return (
	<AutoComplete
		loading={loading}
		suggestions={suggestions}
		value={value}
		onChange={setValue}
		onSearch={(q) => {
			setLoading(true);
			debouncedSearch(q, false);
		}}
		name="fruit"
		placeholder="Type a fruit"
		aria-label="List of fruits"
	/>
);

#Invalid

The Invalid variant, inheriting all states and visual properties, like disabled, invalid, and also visual properties like fullWidth, custom width, large size, leftSlug and rightSlug, etc. from the Input Field component, is designed to indicate erroneous input.

This can include situations where the entered value doesn't match any suggestions, violates validation rules, or is simply left empty. Clear error messages are essential in these scenarios, providing users with information about the issue and guidance on resolving it.

Ideally, data validation should occur before form submission to minimize user frustration. While error messages can highlight empty fields, ensuring proper labeling of required fields beforehand enhances user understanding and reduces the likelihood of error (see Best Practices in Input Field). Follow the writing guideline for Issues and issue descriptions.

Fruit

Some error message to let the user know what's wrong

CodeHTML output

const [value, setValue] = useState("");
return (
	<FormElementWrapper
		label="Fruit"
		name="Fruit"
		invalid
		error="Some error message to let the user know what's wrong"
	>
		<AutoComplete
			suggestions={["Apple", "Banana", "Blueberry", "Cherry"]}
			value={value}
			onChange={setValue}
			placeholder="Type a fruit"
		/>
	</FormElementWrapper>
);

#Disabled

The Disabled variant serves to visually indicate that the component is either temporarily unavailable or not applicable in the current situation. By maintaining the AutoComplete's presence in the layout but preventing user interaction, it ensures a consistent visual experience.

Whenever possible, a hint text or a visual clue (e.g Tooltip) should be included to clarify the reason for the component's disabled state, enhancing the overall user understanding.

CodeHTML output

const [value, setValue] = useState("");
return (
	<AutoComplete
		disabled
		suggestions={["Item 1", "Item 2", "Item 3"]}
		value={value}
		onChange={setValue}
		name="some input"
		placeholder="Placeholder"
		aria-label="List of suggestions"
	/>
);

#Properties

CodePropsHTML output

Property	Description	Defined	Value
valueRequired	`string`Value of the form control	YesNo
onChangeRequired	`function`Callback for onChange event	YesNo
suggestionsRequired	`string[]`List of options to display in the listbox	YesNo
nameOptional	`string`Name applied to the form control	YesNo
idOptional	`string`Id applied to the form control	YesNo
invalidOptional	`boolean`Is the form control invalid	YesNo	truefalse
onBlurOptional	`function`Callback for onBlur event	YesNo
aria-labelOptional	`string`Label of the form control	YesNo
aria-describedbyOptional	`string`ID of an an element that describes what the form control is for	YesNo
aria-labelledbyOptional	`string`ID of an an element that labels this form control	YesNo
onSearchOptional	`function`Handler for searching event	YesNo
caseSensitiveOptional	`boolean`Enables case sensitive highlight	YesNo	truefalse
loadingOptional	`boolean`Display a loading spinner	YesNo	truefalse
placementOptional	`"auto" \| "auto-end" \| "auto-start" \| "bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"`Preferred placement for the popover	YesNo
allowedAutoPlacementsOptional	`literal-union[]`Allowed placements for the popover when using an "auto" value for the "placement" prop	YesNo
disabledOptional	`boolean`	YesNo	truefalse
largeOptional	`boolean`	YesNo	truefalse
widthOptional	`number`	YesNo
autoFocusOptional	`boolean`	YesNo	truefalse
fullWidthOptional	`boolean`	YesNo	truefalse
placeholderOptional	`string`	YesNo
leftSlugOptional	`element`	YesNo
rightSlugOptional	`element`	YesNo
data-observe-keyOptional	`string`Unique string, used by external script e.g. for event tracking	YesNo
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo
tabIndexOptional	`number`Tab index of the outermost HTML element of the component	YesNo
onKeyDownOptional	`function`Callback for onKeyDown event	YesNo
onMouseDownOptional	`function`Callback for onMouseDown event	YesNo
onMouseEnterOptional	`function`Callback for onMouseEnter event	YesNo
onMouseLeaveOptional	`function`Callback for onMouseLeave event	YesNo
onFocusOptional	`function`Callback for onFocus event	YesNo

Filtering through large datasets.
Minimizing user typing effort.
Guiding users towards valid options.

#Placement

Autocomplete is typically used in the following places:

Filters: Autocomplete enables efficient filtering of large lists.
Search Input Field : Provide instant search suggestions to speed up navigation.
Form : Prefill common user information (e.g., addresses, names) to reduce input errors.

#Style

Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your Autocomplete to existing components for visual consistency.
Clearly differentiate the selected suggestion from other options in the list.

#Do not use when

The list of options (< 3) is small and easily scannable.
The input requires free-form text without restrictions.
The context doesn't require quick selection from a predefined list.

#Accessibility

#For designers

Ensure sufficient color contrast between the input field, suggestion list, and any error messages.

#For developers

This component comes with built-in accessibility, no extra work required.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

Keep suggestion labels concise and relevant to the user's input.
Use clear, actionable language for error messages. Follow Issues and issue descriptions.
Provide helpful instructions if the user encounters an empty suggestion list.

Auto Complete

This is a Lab component!

#Examples

#Variant overview:

#Default

#Async

#Invalid

#Disabled

#Properties

#Guidelines

#Best practices

#General

#Placement

#Style

#Do not use when

#Accessibility

#For designers

#For developers

#Writing